MacFormat 1997 February/macformat-047.iso/Shareware Plus/Comms/Mail Router 1.0.4/MailRouter/MailRouter Docs

Text File | 1996-11-24 | 16.1 KB | 212 lines | [ttro/ttxt]

Avalonia MailRouter

How to make Apples Internet Mail Server handle many domains.

The Avalonia MailRouter is an extension to Apples Internet Mail Server (AIMS). It is supposed to be running in the background on the same machine as AIMS, without taking more of the CPU and memory than absolutely needed.
The Avalonia MailRouter is ShareWare. You may try MailRouter out for free, but if you decide to continue using MailRouter, you must pay a ShareWare fee:

• To run a single copy of MailRouter on a single machine, the fee is US$20.
• To run an unlimited amount of copies of MailRouter on machines placed at a single physical location, the fee is US$50.
• To run an unlimited amount of copies of MailRouter on machines inside the same organisation, placed anywhere in the world, the fee is US$100.

Requirements:

To run MailRouter, you need a copy of AIMS, preferably version 1.1.1 or newer, running on a machine with at least a 68030 (or a PowerPC for the PowerPC native version). For best results the machine should be running MacOS System 7.5 or newer.
MailRouter needs at least 100 KB to run, but as the program keeps all needed information in memory all the time, it will allocate more memory, when handling many domains. For a typical site, you should expect a usage between 100 KB and 250 KB. MailRouter will expand its memory usage when needed, so there's no need for you to change the memory partition from the Finder.

Package contents:

The MailRouter package contains the following parts:

• MailRouter 68K — a 68K version of MailRouter. This program will run on both 680X0 and PowerPC machines.
• MailRouter PPC — a native PowerPC version of MailRouter.
• Register — a program that can be used for registering MailRouter.
• How to register — a SimpleText document describing the registration process.
• MailRouter Docs — a SimpleText document describing the usage of MailRouter.
• Revision notes — a SimpleText document describing version changes.
• A sample “alias” file — a SimpleText document containing a sample alias file with 4 domains, showing some usages of MailRouter.

Installation:

•    Place MailRouter in the Startup Items folder in your System Folder of the machine you are running AIMS on, and restart the machine.
•    MailRouter should now be running in the background, so you can now start setting up your domains.

How to set up a domain:

To set up a domain, you must first set up AIMS to handle the domain. To make it work with MailRouter, this must be done in the Sending Setup dialog. Do not enter the domain into the Preferences dialog in AIMS, as this will prevent forwarding of the mail to MailRouter.
AIMS uses a folder named “Mail Folder” in the system folder. When started the first time MailRouter will place a folder named “MailRouter ƒ” in the Mail Folder. This folder contains four folders named “In”, “Spool”, “Log Archive” and “Tmp”. MailRouter expects the messages to be delivered into the “In” folder.
For each domain fill out the Domain field, and set routing to save as files, where the field must contain the full path to the “In” folder. This will ensure that all messages sent to the domain is forwarded to MailRouter. An example of such a path could be:

    Macintosh HD:System Folder:Mail Folder:MailRouter ƒ:In

where the active system folder is placed on the volume “Macintosh HD”.
For AIMS to forward the mail, you must also have set up a DNS entry, with an MX record pointing to your AIMS server, for each domain you want MailRouter to handle.

For MailRouter to forward mail, you first have to create a text file using a text editor, containing a description of how messages should be forwarded. The file must be named “alias” and be placed in the folder “MailRouter ƒ” in the AIMS Mail Folder.
The alias file consists of lines with the following format:

         <keyword> <pattern1> <pattern2> <pattern2> ...

seperated by spaces.

<keyword> can be alias, redirect or popgate, where an alias line is used for forwarding a single address to one or more other addresses, a redirect line is used for redirecting messages to severeal different addresses into a single address, and a popgate line is used for forwarding mail to a domain via a dial-up POP account. If a line doesn’t start with one of these three keywords, the line will be taken as a comment, and skipped by MailRouter.
<pattern1> is a pattern used for matching the addresses on the incoming messages, and <pattern2> is a pattern used for construction the address the message is to be forwarded to. Each line generally allows forwarding to as many addresses you like.

Each time you make a change in the alias file MailRouter will detect the file has been changed, and within 30 seconds of the change having been made, MailRouter will have started using the new information. There is no need for you to restart MailRouter.

alias lines

In alias lines both <pattern1> and <pattern2> are email addresses, as shown in this example:

   alias [e-mail] [e-mail]
   alias [e-mail] [e-mail]
   alias [e-mail] [e-mail]
   alias [e-mail] info

In the example messages to “[e-mail]” are forwarded to “[e-mail]”, messages to “[e-mail]” are forwarded to “[e-mail]”, messages to “[e-mail]” are forwarded to “[e-mail]” and messages to “[e-mail]” are forwarded to “info”.
As you may have noticed from the last line in the example, you can omit the server name on local addresses. If the server used is “avalonia.dk” mail to “[e-mail]” will be forwarded to “[e-mail]”.

An alias line can also contain some special addresses as <pattern2>. An address with a missing account or domain (marked by beginning or ending the address with '@') can be used for broadcasts. Furthermore all messages to addresses resolving to the special address '-' are deleted, without sending a message back to the sender. This comes in handy, if you want to broadcast to all but a few domains.

   alias [e-mail] @cust1.dk
   alias [e-mail] postmaster@
   alias [e-mail] -

The first line shows how to forward all messages sent to “[e-mail]” to all accounts in that has an alias line where <pattern1> has the domain “cust1.dk”. To prevent mail loops MailRouter will exclude “[e-mail]” from the list of addresses the message will be forwarded to. The second line shows how to forward all messages sent to “[e-mail]” to the “postmaster” account at all domains used in <pattern1> in an alias line. The last line shows how to delete all messages sent to “[e-mail]”.

redirect lines

redirect lines are a bit more flexible, as they are used for redirecting mail to several email addresses into a single email address, or to redirect the mail to another mail server:

   redirect cust1.dk [e-mail]
   redirect postmaster [e-mail]
   redirect cust2.dk cust2.com
   redirect olddomain.net -
   redirect [e-mail] mail01.bigcomp.dk
   redirect [e-mail] mail02.bigcomp.dk

Here the first line redirects all messages to email addresses on the domain “cust1.dk” to “[e-mail]”, then all messages to all postmasters on all domains handled by MailRouter are forwarded to “[e-mail]” and all messages to the domain “cust2.dk” are redirected to the domain “cust2.com”. If any messages are sent to an account on the domain “olddomain.net”, those messages will be deleted unread. The two last lines redirects all mail to the domain “mail.bigcomp.dk”, where the accounts begin with an “a” to the server “mail01.bigcomp.dk”, and to “mail02.bigcomp.dk” if the accouts start with a “b”.

There are three forms of patterns:

•    a single word, not containing “.” or “@” is seen by MailRouter as an account, as in “info”.
•    two or more words seperated by “.” is seen by MailRouter as a domain, as in “cust1.dk”.
•    a series of words seperated by a single “@” and one or more “.” is seen by MailRouter as a full email address, such as [e-mail].

<pattern1> can contain untyped wildcards, that can be used to select several accounts or domains. The two last lines in the example are shows how to use an untyped wildcard for splitting mail up between different servers. Actually all lines in the example has an untyped wildcard, as “cust1.dk” accepts all domains ending with “cust1.dk”, and “postmaster” accepts all accounts beginning with “postmaster”.
In some patterns the wildcard can be prevented, by adding a “@” character in front of a domain, or at the end of an account, as shown in the following example:

   redirect @cust1.dk [e-mail]
   redirect postmaster@ [e-mail]
   redirect @cust2.dk cust2.com

When full addresses are used as <pattern1> in a redirect line, MailRouter always uses an untyped wildcard just before and after the “@”.

The rest of the patterns on each line (<pattern2>) are used for describing the destination of the messages, that match <pattern1>. The messages can be forwarded to a full address, but by only giving an account, the message can be forwarded to another account on the same domain. By only giving a domain, the message will be rerouted to another mail server.

   redirect cust1.dk [e-mail]
   redirect cust2.dk cust2.com
   redirect info@ postmaster

In this example the first line redirects all messages to email addresses on the domain “cust1.dk” to “[e-mail]”, all messages to the domain “cust2.dk” to the domain “cust2.com”, and all messages to all accounts managed by MailRouter sent to addresses with the account “info” will be rerouted to the “postmaster” accounts on the same domains.
As <pattern2> has no need for wildcards, “@” signs at the beginning or end of words will be ignored.

Each time you change the contents of the alias file, or put in a new alias file, MailRouter will automatically detect the change, and reinitialize itself with the new information. There is no need for you to restart MailRouter.

popgate lines

The <pattern1> in a popgate line is identical to the <pattern1> in redirect lines, but there can only be one <pattern2>, which must either be a full email address or an account on the local AIMS server:

   popgate cust5.dk [e-mail]
   popgate cust6.dk cust6

In this example all messages to the domain “cust5.dk” and are forwarded to the address “[e-mail]” and all messages to the domain “cust6.dk” are forwarded to the account “cust6” on the local AIMS server.
In both cases it is then up to the customers server software to make a connection to your server to collect the mail. The essential difference between redirect and popgate lines is that when popgate is used extra lines are inserted in each message. The lines inserted are:

   X-Deliver-To: <address>
   X-Real-To: <address>

where <address> contains the address the message originally was sent to. This enables the calling server to place the message into the right mailbox.

Error messages:

All messages that are forwarded to MailRouter, that cannot be resolved — that is they do not match any of the patterns — will normally be put into a waiting queue that will be rechecked the next time the contents of the alias file is changed. MailRouter will also allow you to either forward such messages to a specific address, or bounce them back to the sender and send a report to the postmaster on AIMS.
MailRouter will redirect all messages with addresses that cannot be resolved to a predefined address by adding a single redirect line with “*” as <pattern1>:

   redirect * [e-mail] postmaster

   redirect * oldmail.server.dk

The first example redirects all messages with unresolved addresses to both “[e-mail]” and the postmaster at the domain the message was addressed to, while the second example redirects all messages with unresolved addresses to accounts on the server “oldmail.server.dk”.
If you choose to include a redirect * line, it should be the last line in the alias file. All lines after this line will be ignored.
Also if you overrule the default handling of unresolved addresses, you have to make sure AIMS dosn't route any messages to a new domain to MailRouter, before you have set up that domain. You can ensure this by first changing the alias file, and only then making the changes in AIMS to route the mail to MailRouter.

It is also possible to use a redirect line with only <pattern1>, to bounce mail to specific addresses:

   redirect [e-mail]
            redirect abuse
   redirect oldmail.server.dk
   redirect *

The first line bounces all messages to “[e-mail]”, while the second line bounces all messages addresses beginning with “abuse”. The next line bounces all message to the domain “oldmail.server.dk”, while the last line bounces all messages with unresolved addresses.

As all messages to the accounts “postmaster” and “error-copy” on all domains never should be bounced, any messages with unresolved addresses to those accounts will be forwarded to the “postmaster” account om AIMS. This ensures that mail to the postmaster on any domain always gets delivered, and that the mailserver doesn't get into a loop, where it exchanges error messages with another mail server.

Putting an alias file together:

MailRouter will try to find a match, by comparing the receiving address of a message with <pattern1>, starting from the first line, and continuing with the following line, until a match is found (or the end of the file is reached). It is therefore important, that the lines are put in the right order. If a redirect line is placed before an alias line, the alias line may never be evaluated:

   redirect server.dk [e-mail]
            alias [e-mail] [e-mail]
   alias [e-mail] [e-mail]

In this example, the redirect line catches all messages to the domain “server.dk”, so all messages to the two accounts: “[e-mail]” and “[e-mail]” will end up at “[e-mail]”.
If the redirect is moved down after the two alias lines:

            alias [e-mail] [e-mail]
   alias [e-mail] [e-mail]
   redirect server.dk [e-mail]

mail to the two addresses are forwarded to “[e-mail]”, while mail to other accounts on the domain are forwarded to  “[e-mail]”.

Log format:

MailRouter will create a text file named “log” in the “MailRouter ƒ” folder in the AIMS Mail Folder.
The log file contains one or more lines for each message that has been forwarded by MailRouter, in the following format:

         <time> <date> <AIMS message ID> <size in bytes> <sending address> <receiving address> <address forwarded to>

As each line is tab seperated, it should be easy to import it into a database or a spreadsheet for further processing.
When a message is forwarded to more than one address, the log will contain one line for each address that the message has been forwarded to.
When the size of the log file exceeds 256 KB the contents of the file is moved to a timestamped file in the “Log Archive” folder.

Using MailRouter:

As MailRouter has been designed to run in the background, you will seldom need to pull it to the foreground. Actually MailRouter will do its best to prevent you from doing so.
The only way to move MailRouter to the foreground is by holding the -key down while you select MailRouter in the process menu in the upper right corner.
When pulled to the foreground MailRouter will open a dialog containing three buttons:

• The Reset button will reinitialize MailRouter, by processing any mail waiting to be handled and checking the alias file for modifications.
• The Restart button will restart MailRouter.
• The Quit button allows you to quit MailRouter.

As soon as you press one of the buttons, MailRouter will be sent to the background.

Further information:

Program idea, design and implementation: Bo Holst-Christensen, Cutisan Laboratorium A/S

ShareWare registration: Use the Register program that accompanies the program.

Bug reports can be sent to [e-mail] or [e-mail].

A mailing list has been set up for discussing MacOS mail servers and extensions.
For information on how to subscribe send a message with the body:

     INFO MailTools-L

to the address [e-mail]
Subscribing to the list will also give you access to a file area from where the current version of MailRouter can be fetched via email.

WWW home page: <http://www.avalonia.dk/MailRouter/>